<h1>Directory Deployer</h1>

<p>
A bundle which scans file system directories for files that it can
install, update or uninstall. The directory deployer bundle handles
both bundle files and configuration files.  When a file is updated the
bundle / configuration will be updated and when a file is removed from
the scanned directory the bundle / configuration will be removed.
</p>

<p>
This is a quite useful tool for handle bundle and configuration
deployment without using any console. Just copy the file that should
be installed to the deploy directory, and the directory deployer will
find and activate them. When the files are removed, they are
uninstalled.
</p>


<h2>Deploy method</h2>

<p>The procedure for scanning and deploying is as follows:

<ol>
  <li>
      Check if any new files have appeared or if any already deployed
      files has been replaced with newer files.
  </li>

  <li>
      New files are installed into the framework.<br> At the end of
      the scan any bundle that was installed will be started according
      to its activation policy. Any fragment that was installed will
      be attached to its host (be resolving it).
  </li>

  <li>
      Updated files (newer than a previously deployed bundle) are not
      installed again, instead, the installed bundle or configuration
      is updated from the new file.
  </li>

  <li>
      Check if there are bundles or configurations installed by the
      directory deployer that does not correspond to a file found
      during the directory scan. If any such bundle or configuration
      is found uninstall it.
  </li>

  <li>
      If any bundle update was performed during the scan, perform a
      refresh bundles operation for them using the in the framework
      wiring API.
  </li>

  <li>
      Start newly installed bundles that can be started, resolve newly
      installed fragments. Note that there will only be one start /
      resolve attempt made for each bundle after an install or update.
  </li>

  <li>
      Sleep a while
  </li>

  <li>
      Repeat from 1.
  </li>

</ol>

<h2>Deployable File Types</h2>

The Directory Deployer supports deploying of bundles and configurations:

<ul>

  <li><b><tt>*.jar</tt></b> Bundle jar files.

  <li><b><tt>*.xml</tt></b> OSGi CM configurations stored in XML-files
      using the DTD <a href="../cm/cm_data.dtd">cm_data.dtd</a>.

</ul>
      
<p>

  A sample XML-file with a configuration for the Directory Deployer
  bundle itself can be <a href="dirdeployer.xml">downloaded here</a>.

</p>
<p>

  To create a CM configuration from scratch one may use the CM-tab in
  Knopflerfish desktop, it presents a simple GUI based on
  configuration meta type descriptions provided by configurable
  bundles. The CM-tab is not visible in the Desktop when starting with
  the default set of bundles, to activate it one must install and
  start three more bundles from the Knopflerfish distribution:
  <tt>metatype</tt> (OSGi Metatyp APIs), <tt>kf_metatype_all</tt>
  (Knopflerfish Metatyp Service implementation) and
  <tt>cm_desktop</tt> (the CM-tab desktop plug in itself).

</p>
<p>

  To save an existing CM configuration as cm_data XML one may use the
  CM-tab in the Knopflerfish desktop, it provides an
  <tt>Export...</tt> button that will export the current configuration
  as a cm_data XML file. It is also possible to use the Knopflerfish
  console command <tt>configuration export</tt>. See <a
  href="../cm_cmd/index.html">CM Commands</a> for details.  Avoid
  writing cm_data XML files by hand since the parser for the
  <tt>cm_data</tt> XML documents is written for machine generated
  documents so it does not give usable error messages when something
  in the XML-document is wrong.

</p>



<h2>Configuration</h2>

<p>

  See <a
  href="$(GIT_REPO_URL)/$(GIT_TAG)/osgi/bundles_opt/dirdeployer/resources/OSGI-INF/metatype/metatype.xml">metatype.xml</a>
  for specification using CM. The same properties as defined by CM are
  also read as default values from framework properties. Thus, the
  bundle can be both configured by CM and using system properties.

</p>
<p>

  You can set the deployment directory in <tt>metatype.xml</tt> in the
  bundle's resource directory (defaults to <tt>./load</tt>). A
  relative deployment directory path is relative to the directory from
  which the framework is started.

</p>
<p>

  The table below describes the framework properties that may be used
  to set the default values for the directory deployer configuration.
</p>
<p>
<table class="man">
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.dir</td>
    <td>

	Set the directories that should be scanned.

	<p>The value should be a comma-separated list of directory
	paths.</p>

    </td>
    <td>String</td>
    <td>./load</td>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.poll</td>
    <td>

	Poll interval in milliseconds between directory scans. Must be
	at least 100 ms. 

    </td>
    <td>long</td>
    <td>1000</td>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.use.initial.startlevel</td>
    <td>

	<p>

        When this property is true the Directory Deployer will not set
	any start level for bundles it installs thus those bundles
	will belong to the default start level (i.e., the current
	initial start level according to the Framework Start Level
	API).

	</p><p>

	When this property is false the Directory Deployer will assign
	the start level given by
	<tt>org.knopflerfish.fileinstall.startlevel</tt> to the
	bundles it installs.

	</p>

    </td>
    <td>boolean</td>
    <td>true</td>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.startlevel</td>
    <td>

	Bundle start level to assign to all newly installed
	bundles. Note that you must set
	<tt>org.knopflerfish.fileinstall.startlevel</tt> to false for
	this property to have an effect.

    </td>
    <td>int</td>
    <td>

      The initial bundle start level as returned by the
      StartLevel-API.

    </td>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.uninstallOnStop</td>
    <td>

	If <code>true</code> then the directory deployer will
        uninstall all bundles and configurations that it has installed
        when it stops.

    </td>
    <td>boolean</td>
    <td>true</td>
  </tr>

  <tr>
    <td>org.knopflerfish.fileinstall.filemarkers.use</td>
    <td>
      When set to true the deployer will use a suffix file marker to identify and mark files to deploy as
      well as their deployment status. The following markers are used:
      <p>
      <table class="man_inner">
	<tr>
	  <td>.dodeploy</td>
	  <td> Mark the file for deployment </td>
	</tr>
	<tr>
	  <td>.deploying</td>
	  <td>The file is in the process of being deployed </td>
	</tr>
	<tr>
	  <td>.deployed </td>
	  <td>The file has been succesfully deployed. Removing this marker will undeploy the file </td>
	</tr>
	<tr>
	  <td>.undeploying </td>
	  <td>The file is in the process of being undeployed </td>
	</tr>
	<tr>
	  <td>.undeployed </td>
	  <td>The file has been successfully deployed </td>
	</tr>
	<tr>
	  <td>.failed </td>
	  <td>A deployment step failed. Removing this marker will make the file eligable for
	    deployment again</td>
	</tr>
      </table>
      </p>
    </td>
    <td>boolean</td>
    <td>false</td>
  </tr>
  <tr>
    <td>org.knopflerfish.fileinstall.bundlecontrols.use</td>
    <td>
      When set to true a DeployedBundleControl instance is registered for every deployed bundle jar file.
    <td>boolean</td>
    <td>false</td>
    
</table>
</p>
